Subscriptions: Results

Subscriptions: Results

#340750

Description

The /subscriptions/<platformType>/<subscriptionRef> resource is used to dynamically retrieve your latest personalized Densify subscription recommendations. This resource allows you to review your platform-specific subscription results on-demand. The same information is delivered to a third-party application for targeted distribution if the third-party application is defined in the subscription's webhook.

To see how subscriptions are defined, refer to Subscriptions.

Resource

/subscriptions/cloud/<subscriptionRef>

/subscriptions/containers/<subscriptionRef>

/subscriptions/<subscriptionRef>

Note: If you use this resource without the <platformType> specified (i.e. without cloud or containers specified), the behavior is exactly the same as specifying the cloud-specific resource. This behavior enables backward compatibility with scripts using the Densify API prior to release 12.1.6, where the platform-specific indicator was not available.

Supported Operations

Table: Subscription Results Supported Operations

HTTP Method

Input

Output

Description

GET /subscriptions/<platformType>/<subscriptionRef>

Path Parameter:

Query String Parameter:

subscription:

  • collection of personalized recommendations in the format defined by returnStructure

Returns the current results of the platform-specific subscription notification, identified by <subscriptionRef>.

The returned output is the same information that is delivered to the webhook application if the subscription is scheduled to run at the current time. Note that the following parameters are ignored for on-demand subscription results request:

  • active—results are always returned for on-demand requests, even if "active": "false";
  • webhook—results are always returned for on-demand requests, even if webhook is undefined;
  • schedule—results are always returned for on-demand requests, regardless of the notification schedule defined.

An appropriate error message and HTTP code are returned for failed requests. See Returned Status

See Example: Getting On-Demand Subscription Cloud Results

Parameters

Path Parameters

Table: Subscription Results Path Parameters

Parameter Name

Type

Required

Description

platformType

string

Y

[cloud|containers]

Specify the technology platform for the subscription results resource.

subscriptionRef

string

Y

Specify the unique subscription identifier.

Query String Parameters

Table: Subscription Results Query String Parameters

Parameter Name

Type

Required (Y/N)

Description

divider

string

[true|false]

 

An option to display a divider that separates properties and tags for each system in the output:

  • true (default)—show the divider:

    • "divider": "------------------------",

  • false—do not show the divider.

Note: The divider is not displayed in the output for scheduled subscription results sent to webhooks.

limit

number

range [1:30000]

 

An option to set the limit of returned results.

By default, the limit is set to 3000. This implies that the number of results returned is limited to 3000 systems. If a subscription's result count is more than 3000 system recommendations, an error is returned with code 400. If this is the case, you can adjust your on-demand subscription request to a higher limit. For example: ?limit=8000.

The range of the limit value is from 1 to 30000.

Note: This limit does not apply to subscription recommendations sent to webhooks. It only applies to on-demand subscription queries, and hence, will negatively impact web server performance if the limit is set too high.

See Example: On-Demand Subscription Results Count Exceeding Limit.

Response

The following is a complete list of possible response elements returned for the /subscriptions/<platformType>/<subscriptionRef> resource.

Table: Subscription Results Response Schema

Element

Type

Filter/Sort

Description

Subscription Information

subscription

  

Subscription header information. See:

name

string

  

The subscription name.

description

string

  

The subscription description.

created

datetime

 

The date and time when the subscription entity was created.

createdBy

string

 

The authenticated Densify user who created the subscription.

updated

datetime

 

The date and time when the subscription was last modified.

updatedBy

string

 

The authenticated Densify user who modified the subscription.

lastRefreshed

datetime

  

The date, and time of the last recommendation analysis. This is typically scheduled to run nightly after data collection.

owner

string

 

The designated owner of the subscription. This field contains the Densify username of the owner.

The subscription is considered global if this element is empty and private otherwise.

Subscription Results

count

number

 

The number of system recommendations in the results collection.

results

array of returnStructure

 

An array of system results, with properties and tags defined in the subscription's returnStructure.

Refer to Subscriptions: returnStructure for details on how the returnStructure can be defined. Below are the possible elements returned for each system recommendation:

  • properties—the list of properties defined in the returnStructure (if no returnStructure is defined, all recommendation properties are returned);
  • divider—the divider element between properties and tags (if defined): 

    • "divider": "------------------------",

  • tags—the list of attribute tags defined in the returnStructure.

Refer to the various cloud or container recommendation resource topics for a description of each result element: Analysis: AWS Recommendations: Response, Analysis: Azure Recommendations: Response, Analysis: GCP Recommendations: Response, and Analysis: Kubernetes Container Recommendations: Response.

Returned Status

message

string

 

The message for the status response is returned.

See Example: On-Demand Subscription Results Count Exceeding Limit for an example of HTTP 400 Bad Request error message.

status

number

 

The HTTP response code of the request. Possible status values include:

  • 200—success with request (usually with content in response body);
  • 204—success with request, no content returned;
  • 400—bad request (invalid parameters, logical errors);
  • 401—authentication failed;
  • 404—resource not found (or no privileges);
  • 415—unsupported media type;
  • 500—internal server error.

Examples

Example: Getting On-Demand Subscription Cloud Results

The following example shows you how to retrieve your subscription cloud results, on-demand.

Request:

Copy 
GET /subscriptions/cloud/fa3be33c-fbb7-4912-88c2-a83ee58e444e

Response:

Copy 
{
    "subscription": {
        "name": "Sample Subscription",
        "description": "A subscription for testing",
        "created": "Mon Jan 19 13:52:31 EST 2020",
        "createdBy": "saas",
        "updated": "Mon Jan 20 14:32:38 EST 2020",
        "updatedBy": "SaaSadmin",
        "lastRefreshed": "Mon Jan 20 01:32:59 EST 2020",
        "owner": "saas"
        },
    "count": 452,
    "results": [
        {
          "currentType": "standard_d2",
          "name": "st01-prepro-edge-307",
          "recommendationType": "Modernize - Optimal Family",
          "savingsEstimate": "43.850475",
          "serviceType": "Virtual Machine",
          "divider": "------------------------",
          "Availability Zone": "eastus+group"
        },
        {
          "currentType": "r3.2xlarge",
          "name": "ex-prepro-stoc-384",
          "recommendationType": "Downsize",
          "savingsEstimate": "75.36128",
          "serviceType": "EC2",
          "divider": "------------------------",
          "Resource Tags": 
            [
             "Owner : Bob Snow",
             "Product Code : PR000263",
             "Environment : Pre-prod",
             "Inventory Code : prepro-stoc",
             "Name : ex-prepro-stoc-384"
            ],
          "Availability Zone": "us-east-1d"
        },
        {
        // ... *SNIP* additional 450 system recommendations not displayed *SNIP* ...
        }
    ]
}

Example: On-Demand Subscription Results Count Exceeding Limit

If your on-demand Subscriptions request contains a large number of results, exceeding the results limit, you will encounter an HTTP 400 Bad Request error message with the count limit.

Request:

Copy 
GET /subscriptions/cloud/489331bd-5db9-408d-b7a0-2f3f8b1f66e9

Response:

Copy 
{
    "message": "On-Demand Failure. The return count of 3891 has exceeded object return limit of 3000. Update your call with a new limit value. Wed Jul 29 09:05:15 EDT 2020",
    "status": 400
}

This error is returned only for on-demand Subscriptions results requests with results count exceeding the default count limit. Subscription results sent to webhooks do not have a count limit. You can override this limit by requesting the on-demand results again with an increased limit count in the URL query string. Note that increasing the results limit may affect response time of the Densify web server.

Request with increased limit count:

Copy 
GET /subscriptions/cloud/489331bd-5db9-408d-b7a0-2f3f8b1f66e9?limit=4000